<div id="Tags"></div>
<div class="header">
<p>
Next: [[cvs: Specifying what to tag from the working directory#Specifying what to tag from the working directory|Tagging the working directory]], Previous: [[cvs: Assigning revisions#Assigning revisions|Assigning revisions]], Up: [[cvs: Revisions#Revisions|Revisions]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>

----

<div id="Tags_002d_002dSymbolic-revisions"></div>
=== Tags&ndash;Symbolic revisions ===
<div id="index-Tags"></div>

The revision numbers live a life of their own.  They
need not have anything at all to do with the release
numbers of your software product.  Depending
on how you use <small>CVS</small> the revision numbers might change several times
between two releases.  As an example, some of the
source files that make up <small>RCS</small> 5.6 have the following
revision numbers:
<div id="index-RCS-revision-numbers"></div>

<div class="example" style="margin-left: 3.2em">
 ci.c            5.21
 co.c            5.9
 ident.c         5.3
 rcs.c           5.12
 rcsbase.h       5.11
 rcsdiff.c       5.10
 rcsedit.c       5.11
 rcsfcmp.c       5.9
 rcsgen.c        5.10
 rcslex.c        5.11
 rcsmap.c        5.2
 rcsutil.c       5.10
</div>

<div id="index-tag-_0028subcommand_0029_002c-introduction"></div>
<div id="index-Tags_002c-symbolic-name"></div>
<div id="index-Symbolic-name-_0028tag_0029"></div>
<div id="index-Name_002c-symbolic-_0028tag_0029"></div>
<div id="index-HEAD_002c-as-reserved-tag-name"></div>
<div id="index-BASE_002c-as-reserved-tag-name"></div>
You can use the <code>tag</code> command to give a symbolic name to a
certain revision of a file.  You can use the &lsquo;<code>-v</code>&rsquo; flag to the
<code>status</code> command to see all tags that a file has, and
which revision numbers they represent.  Tag names must
start with an uppercase or lowercase letter and can
contain uppercase and lowercase letters, digits,
&lsquo;<code>-</code>&rsquo;, and &lsquo;<code>_</code>&rsquo;.  The two tag names <code>BASE</code>
and <code>HEAD</code> are reserved for use by <small>CVS</small>.  It
is expected that future names which are special to
<small>CVS</small> will be specially named, for example by
starting with &lsquo;<code>.</code>&rsquo;, rather than being named analogously to
<code>BASE</code> and <code>HEAD</code>, to avoid conflicts with
actual tag names.

You&rsquo;ll want to choose some convention for naming tags,
based on information such as the name of the program
and the version number of the release.  For example,
one might take the name of the program, immediately
followed by the version number with &lsquo;<code>.</code>&rsquo; changed to
&lsquo;<code>-</code>&rsquo;, so that <small>CVS</small> 1.9 would be tagged with the name
<code>cvs1-9</code>.  If you choose a consistent convention,
then you won&rsquo;t constantly be guessing whether a tag is
<code>cvs-1-9</code> or <code>cvs1_9</code> or what.  You might
even want to consider enforcing your convention in the
taginfo file (see [[cvs: User-defined logging#User-defined logging|user-defined logging]]).

<div id="index-Adding-a-tag"></div>
<div id="index-Tags_002c-example"></div>
The following example shows how you can add a tag to a
file.  The commands must be issued inside your working
directory.  That is, you should issue the
command in the directory where &lsquo;<tt>backend.c</tt>&rsquo;
resides.

<div class="example" style="margin-left: 3.2em">
 $ cvs tag rel-0-4 backend.c
 T backend.c
 $ cvs status -v backend.c
 ===================================================================
 File: backend.c         Status: Up-to-date
 
     Version:            1.4     Tue Dec  1 14:39:01 1992
     RCS Version:        1.4     /u/cvsroot/yoyodyne/tc/backend.c,v
     Sticky Tag:         (none)
     Sticky Date:        (none)
     Sticky Options:     (none)
 
     Existing Tags:
         rel-0-4                     (revision: 1.4)
 
</div>

For a complete summary of the syntax of <code>cvs tag</code>,
including the various options, see [[cvs: Quick reference to CVS commands#Quick reference to CVS commands|Invoking CVS]].

There is seldom reason to tag a file in isolation.  A more common use is
to tag all the files that constitute a module with the same tag at
strategic points in the development life-cycle, such as when a release
is made.

<div class="example" style="margin-left: 3.2em">
 $ cvs tag rel-1-0 .
 cvs tag: Tagging .
 T Makefile
 T backend.c
 T driver.c
 T frontend.c
 T parser.c
</div>

(When you give <small>CVS</small> a directory as argument, it generally applies the
operation to all the files in that directory, and (recursively), to any
subdirectories that it may contain.  See [[cvs: Recursive behavior#Recursive behavior|Recursive behavior]].)

<div id="index-Retrieving-an-old-revision-using-tags"></div>
<div id="index-Tags_002c-retrieving-old-revisions"></div>
The <code>checkout</code> command has a flag, &lsquo;<code>-r</code>&rsquo;, that lets you check out
a certain revision of a module.  This flag makes it easy to
retrieve the sources that make up release 1.0 of the module &lsquo;<code>tc</code>&rsquo; at
any time in the future:

<div class="example" style="margin-left: 3.2em">
 $ cvs checkout -r rel-1-0 tc
</div>

This is useful, for instance, if someone claims that there is a bug in
that release, but you cannot find the bug in the current working copy.

You can also check out a module as it was at any given date.
See [[cvs: checkout options#checkout options|checkout options]].  When specifying &lsquo;<code>-r</code>&rsquo; to
any of these commands, you will need beware of sticky
tags; see [[cvs: Sticky tags#Sticky tags|Sticky tags]].

When you tag more than one file with the same tag you
can think about the tag as &quot;a curve drawn through a
matrix of filename vs. revision number.&quot;  Say we have 5
files with the following revisions:

<div class="example" style="margin-left: 3.2em">
         file1   file2   file3   file4   file5
 
         1.1     1.1     1.1     1.1  /--1.1*      &lt;-*-  TAG
         1.2*-   1.2     1.2    -1.2*-
         1.3  \- 1.3*-   1.3   / 1.3
         1.4          \  1.4  /  1.4
                       \-1.5*-   1.5
                         1.6
</div>

At some time in the past, the <code>*</code> versions were tagged.
You can think of the tag as a handle attached to the curve
drawn through the tagged revisions.  When you pull on
the handle, you get all the tagged revisions.  Another
way to look at it is that you &quot;sight&quot; through a set of
revisions that is &quot;flat&quot; along the tagged revisions,
like this:

<div class="example" style="margin-left: 3.2em">
         file1   file2   file3   file4   file5
 
                         1.1
                         1.2
                 1.1     1.3                       _
         1.1     1.2     1.4     1.1              /
         1.2*----1.3*----1.5*----1.2*----1.1     (--- &lt;--- Look here
         1.3             1.6     1.3              \_
         1.4                     1.4
                                 1.5
</div>


----

<div class="header">
<p>
Next: [[cvs: Specifying what to tag from the working directory#Specifying what to tag from the working directory|Tagging the working directory]], Previous: [[cvs: Assigning revisions#Assigning revisions|Assigning revisions]], Up: [[cvs: Revisions#Revisions|Revisions]] &nbsp; |[[cvs: Index#SEC_Contents|Contents]]||[[cvs: Index#Index|Index]]|</p>
</div>
This document was generated on <i>a sunny day</i> using [http://www.nongnu.org/texi2html/ <i>texi2html</i>].
